<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Boost.Container and C++ exceptions</title>
<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset">
<link rel="up" href="../container.html" title="Chapter 9. Boost.Container">
<link rel="prev" href="main_features.html" title="Main features">
<link rel="next" href="non_standard_containers.html" title="Non-standard containers">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td>
<td align="center"><a href="../../../index.html">Home</a></td>
<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="main_features.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../container.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="non_standard_containers.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="container.exception_handling"></a><a class="link" href="exception_handling.html" title="Boost.Container and C++ exceptions">Boost.Container and C++ exceptions</a>
</h2></div></div></div>
<p>
      In some environments, such as game development or embedded systems, C++ exceptions
      are disabled or a customized error handling is needed. According to document
      <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2271.html" target="_top">N2271
      EASTL -- Electronic Arts Standard Template Library</a> exceptions can be
      disabled for several reasons:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
          <span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling incurs some kind of cost in all compiler
          implementations, including those that avoid the cost during normal execution.
          However, in some cases this cost may arguably offset the cost of the code
          that it is replacing.</em></span></span>”</span>
        </li>
<li class="listitem">
          <span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling is often agreed to be a superior solution
          for handling a large range of function return values. However, avoiding
          the creation of functions that need large ranges of return values is superior
          to using exception handling to handle such values.</em></span></span>”</span>
        </li>
<li class="listitem">
          <span class="quote">“<span class="quote"><span class="emphasis"><em>Using exception handling correctly can be difficult in
          the case of complex software.</em></span></span>”</span>
        </li>
<li class="listitem">
          <span class="quote">“<span class="quote"><span class="emphasis"><em>The execution of throw and catch can be significantly
          expensive with some implementations.</em></span></span>”</span>
        </li>
<li class="listitem">
          <span class="quote">“<span class="quote"><span class="emphasis"><em>Exception handling violates the don't-pay-for-what-you-don't-use
          design of C++, as it incurs overhead in any non-leaf function that has
          destructible stack objects regardless of whether they use exception handling.</em></span></span>”</span>
        </li>
<li class="listitem">
          <span class="quote">“<span class="quote"><span class="emphasis"><em>The approach that game software usually takes is to avoid
          the need for exception handling where possible; avoid the possibility of
          circumstances that may lead to exceptions. For example, verify up front
          that there is enough memory for a subsystem to do its job instead of trying
          to deal with the problem via exception handling or any other means after
          it occurs.</em></span></span>”</span>
        </li>
<li class="listitem">
          <span class="quote">“<span class="quote"><span class="emphasis"><em>However, some game libraries may nevertheless benefit
          from the use of exception handling. It's best, however, if such libraries
          keep the exception handling internal lest they force their usage of exception
          handling on the rest of the application.</em></span></span>”</span>
        </li>
</ul></div>
<p>
      In order to support environments without C++ exception support or environments
      with special error handling needs, <span class="bold"><strong>Boost.Container</strong></span>
      changes error signalling behaviour when <code class="computeroutput"><span class="identifier">BOOST_CONTAINER_USER_DEFINED_THROW_CALLBACKS</span></code>
      or <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code> is defined.
      The former shall be defined by the user and the latter can be either defined
      by the user or implicitly defined by <span class="bold"><strong>Boost.Confg</strong></span>
      when the compiler has been invoked with the appropriate flag (like <code class="computeroutput"><span class="special">-</span><span class="identifier">fno</span><span class="special">-</span><span class="identifier">exceptions</span></code> in GCC).
    </p>
<p>
      When dealing with user-defined classes, (e.g. when constructing user-defined
      classes):
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
          If <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code>
          is defined, the library avoids using <code class="computeroutput"><span class="keyword">try</span></code>/<code class="computeroutput"><span class="keyword">catch</span></code>/<code class="computeroutput"><span class="keyword">throw</span></code>
          statements. The class writer must handle and propagate error situations
          internally as no error will be propagated through <span class="bold"><strong>Boost.Container</strong></span>.
        </li>
<li class="listitem">
          If <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code>
          is <span class="bold"><strong>not</strong></span> defined, the library propagates
          exceptions offering the exception guarantees detailed in the documentation.
        </li>
</ul></div>
<p>
      When the library needs to throw an exception (such as <code class="computeroutput"><span class="identifier">out_of_range</span></code>
      when an incorrect index is used in <code class="computeroutput"><span class="identifier">vector</span><span class="special">::</span><span class="identifier">at</span></code>), the
      library calls a throw-callback declared in <code class="computeroutput"><a class="link" href="../boost_container_header_reference.html#header.boost.container.throw_exception_hpp" title="Header &lt;boost/container/throw_exception.hpp&gt;">boost/container/throw_exception.hpp</a></code>:
    </p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
          If <code class="computeroutput"><span class="identifier">BOOST_CONTAINER_USER_DEFINED_THROW_CALLBACKS</span></code>
          is defined, then the programmer must provide its own definition for all
          <code class="computeroutput"><span class="identifier">throw_xxx</span></code> functions. Those
          functions can't return, they must throw an exception or call <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">exit</span></code> or <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">abort</span></code>.
        </li>
<li class="listitem">
          Else if <code class="computeroutput"><span class="identifier">BOOST_NO_EXCEPTIONS</span></code>
          is defined, a <code class="computeroutput"><span class="identifier">BOOST_ASSERT_MSG</span></code>
          assertion is triggered (see <a href="http://www.boost.org/libs/utility/assert.html" target="_top">Boost.Assert</a>
          for more information). If this assertion returns, then <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">abort</span></code>
          is called.
        </li>
<li class="listitem">
          Else, an appropriate standard library exception is thrown (like <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">out_of_range</span></code>).
        </li>
</ul></div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2009-2018 Ion Gaztanaga<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="main_features.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../container.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="non_standard_containers.html"><img src="../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
